Next: Programming Example, Previous: Introduction, Up: Top [Contents][Index]
A form consists of read only text for documentation and some fields, where each field contains two parts, a tag and a value. The tags are used to identify the fields, so the documentation can refer to the ‘foo field’, meaning the field tagged with ‘Foo’. Here is an example form:
Here is some documentation. Name: My Name Choose: This option Address: Some Place In some City Some country. See also _other work_ for more information. Numbers: count to three below [INS] [DEL] One [INS] [DEL] Eh, two? [INS] [DEL] Five! [INS] Select multiple: [X] This [ ] That [X] Thus Select one: (*) One ( ) Another One. ( ) A Final One. [Apply Form] [Reset Form]
The top level widgets in this example are tagged ‘Name’, ‘Choose’, ‘Address’, ‘_other work_’, ‘Numbers’, ‘Select multiple’, ‘Select one’, ‘[Apply Form]’, and ‘[Reset Form]’. There are basically two things the user can do within a form, namely editing the editable text fields and activating the buttons.
In the example, the value for the ‘Name’ is most likely displayed in an editable text field, and so are values for each of the members of the ‘Numbers’ list. All the normal Emacs editing operations are available for editing these fields. The only restriction is that each change you make must be contained within a single editable text field. For example, capitalizing all text from the middle of one field to the middle of another field is prohibited.
Editable text fields are created by the
editable-field widget.
Warning: In an editable-field
widget, the editable field must not be adjacent to another
widget—that won’t work. You must put some text in
between. Either make this text part of the
editable-field widget itself, or insert it with
widget-insert.
The :format keyword is useful for generating the
necessary text; for instance, if you give it a value of
"Name: %v ", the ‘Name: ’
part will provide the necessary separating text before the field
and the trailing space will provide the separating text after the
field. If you don’t include the :size keyword,
the field will extend to the end of the line, and the terminating
newline will provide separation after.
Warning: In an editable-field
widget, the ‘%v’ escape must be preceded
by some other text in the :format string (if
specified).
The editing text fields are highlighted with the
widget-field-face face, making them easy to
find.
Face used for other editing fields.
Some portions of the buffer have an associated action, which can be invoked by a standard key or mouse command. These portions are called buttons. The default commands for activating a button are:
Invoke the button at pos, defaulting to
point. If point is not located on a button, invoke the
binding in widget-global-map (by default the
global map).
Invoke the button at the location of the mouse
pointer. If the mouse pointer is located in an editable
text field, invoke the binding in
widget-global-map (by default the global
map).
There are several different kind of buttons, all of which are present in the example:
When you invoke one of these buttons, you will be asked to
choose between a number of different options. This is how you
edit an option field. Option fields are created by the
menu-choice widget. In the example,
‘Choose’ is an option field
tag.
Activating these will insert or delete elements from an
editable list. The list is created by the
editable-list widget.
The ‘_other work_’ is an
example of an embedded button. Embedded buttons are not
associated with any fields, but can serve any purpose, such
as implementing hypertext references. They are usually
created by the link widget.
Activating one of these will convert it to the other. This
is useful for implementing multiple-choice fields. You can
create them with the checkbox widget.
Only one radio button in a
radio-button-choice widget can be selected at
any time. When you invoke one of the unselected radio
buttons, it will be selected and the previous selected radio
button will become unselected.
These are explicit buttons made with the
push-button widget. The main difference from the
link widget is that the buttons will be
displayed as GUI buttons when possible.
To make them easier to locate, buttons are emphasized in the buffer.
Face used for buttons.
Face used for highlighting a button when the mouse pointer moves across it.
You can use all the normal Emacs commands to move around in a form buffer, plus you will have these additional commands:
Move point count buttons or editing fields forward.
Move point count buttons or editing fields backward.
Next: Programming Example, Previous: Introduction, Up: Top [Contents][Index]